home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / SetResult.3 < prev    next >
Text File  |  1995-07-17  |  11KB  |  344 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/SetResult.3,v 1.12 93/04/03 15:05:59 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_SetResult tclc 7.0
  206. .BS
  207. .SH NAME
  208. Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. \fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
  214. .sp
  215. \fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
  216. .sp
  217. .VS
  218. \fBTcl_AppendElement\fR(\fIinterp, string\fR)
  219. .VE
  220. .sp
  221. \fBTcl_ResetResult\fR(\fIinterp\fR)
  222. .sp
  223. \fBTcl_FreeResult\fR(\fIinterp\fR)
  224. .SH ARGUMENTS
  225. .AS Tcl_FreeProc freeProc
  226. .AP Tcl_Interp *interp out
  227. Interpreter whose result is to be modified.
  228. .AP char *string in
  229. String value to become result for \fIinterp\fR or to be
  230. appended to existing result.
  231. .AP Tcl_FreeProc freeProc in
  232. Address of procedure to call to release storage at
  233. \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
  234. \fBTCL_VOLATILE\fR.
  235. .BE
  236.  
  237. .SH DESCRIPTION
  238. .PP
  239. The procedures described here are utilities for setting the
  240. result/error string in a Tcl interpreter.
  241. .PP
  242. \fBTcl_SetResult\fR
  243. arranges for \fIstring\fR to be the return string for the current Tcl
  244. command in \fIinterp\fR, replacing any existing result.
  245. If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
  246. refers to an area of static storage that is guaranteed not to be
  247. modified until at least the next call to \fBTcl_Eval\fR.
  248. If \fIfreeProc\fR
  249. is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
  250. to \fBmalloc()\fR and is now the property of the Tcl system.
  251. \fBTcl_SetResult\fR will arrange for the string's storage to be
  252. released by calling \fBfree()\fR when it is no longer needed.
  253. If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
  254. points to an area of memory that is likely to be overwritten when
  255. \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
  256. In this case \fBTcl_SetResult\fR will make a copy of the string in
  257. dynamically allocated storage and arrange for the copy to be the
  258. return string for the current Tcl command.
  259. .PP
  260. If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
  261. \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
  262. of a procedure that Tcl should call to free the string.
  263. This allows applications to use non-standard storage allocators.
  264. When Tcl no longer needs the storage for the string, it will
  265. call \fIfreeProc\fR.  \fIFreeProc\fR should have arguments and
  266. result that match the type \fBTcl_FreeProc\fR:
  267. .nf
  268. .RS
  269.  
  270. typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
  271.  
  272. .RE
  273. .fi
  274. When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
  275. the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
  276. .PP
  277. If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
  278. and \fBTcl_SetResult\fR
  279. re-initializes \fIinterp\fR's result to point to the pre-allocated result
  280. area, with an empty string in the result area.
  281. .PP
  282. If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
  283. result, \fBTcl_SetResult\fR does whatever is necessary to dispose
  284. of the old result (see the \fBTcl_Interp\fR manual entry for details
  285. on this).
  286. .PP
  287. \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
  288. It takes each of its \fIstring\fR arguments and appends them in order
  289. to the current result associated with \fIinterp\fR.
  290. If the result is in its initialized empty state (e.g. a command procedure
  291. was just invoked or \fBTcl_ResetResult\fR was just called),
  292. then \fBTcl_AppendResult\fR sets the result to the concatenation of
  293. its \fIstring\fR arguments.
  294. \fBTcl_AppendResult\fR may be called repeatedly as additional pieces
  295. of the result are produced.
  296. \fBTcl_AppendResult\fR takes care of all the
  297. storage management issues associated with managing \fIinterp\fR's
  298. result, such as allocating a larger result area if necessary.
  299. Any number of \fIstring\fR arguments may be passed in a single
  300. call;  the last argument in the list must be a NULL pointer.
  301. .PP
  302. \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
  303. that it allows results to be built up in pieces.
  304. However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
  305. argument and it appends that argument to the current result
  306. as a proper Tcl list element.
  307. \fBTcl_AppendElement\fR adds backslashes or braces if necessary
  308. to ensure that \fIinterp\fR's result can be parsed as a list and that
  309. \fIstring\fR will be extracted as a single element.
  310. Under normal conditions, \fBTcl_AppendElement\fR will add a space
  311. character to \fIinterp\fR's result just before adding the new
  312. list element, so that the list elements in the result are properly
  313. separated.
  314. .VS
  315. However if the new list element is the first in a list or sub-list
  316. (i.e. \fIinterp\fR's current result is empty, or consists of the
  317. single character ``{'', or ends in the characters `` {'') then no
  318. space is added.
  319. .VE
  320. .PP
  321. \fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
  322. freeing the memory associated with it if the current result was
  323. dynamically allocated.
  324. It leaves the result in its normal initialized state with
  325. \fIinterp->result\fR pointing to a static buffer containing
  326. \fBTCL_RESULT_SIZE\fR characters, of which the first character
  327. is zero.
  328. \fBTcl_ResetResult\fR also clears the error state managed by
  329. \fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
  330. .PP
  331. \fBTcl_FreeResult\fR is a macro that performs part of the work
  332. of \fBTcl_ResetResult\fR.
  333. It frees up the memory associated with \fIinterp\fR's result
  334. and sets \fIinterp->freeProc\fR to zero, but it doesn't
  335. change \fIinterp->result\fR or clear error state.
  336. \fBTcl_FreeResult\fR is most commonly used when a procedure
  337. is about to replace one result value with another.
  338.  
  339. .SH "SEE ALSO"
  340. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  341.  
  342. .SH KEYWORDS
  343. append, command, element, list, result, return value, interpreter
  344.